/*
Copyright 2009 Johan Maasing, Mikael Forsberg

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package com.google.code.pj2r;

/**
 * Controller for operating on resources. Contains the CRUD and List methods
 * that the dispatcher servlet delegates to depending on the HTTP call recieved.
 */
public interface Resource {

	/**
	 * Create a list of known resources. This is in response to a GET request.
	 * @return The resulting array of resources. May not return null.
	 * @throws DataAccessException If there is a problem with obtaining the list
	 * of resources.
	 * @throws MarshallingException If serialization to JSON fails.
	 */
	public abstract String list() throws DataAccessException, MarshallingException;

	/**
	 * Create the JSON representation of a single resource. This is in response
	 * to a GET request where the URL contains an identifier for the resource.
	 * @param id The identifier of the resource to retreive. Never null.
	 * @return The JSON representation of the resource. Null if the resource
	 * can not be found.
	 * @throws DataAccessException If there is a problem with retreiving the resouce.
	 * @throws MarshallingException If the serialization to JSON fails.
	 */
	public abstract String get(String id) throws DataAccessException, MarshallingException;

	/**
	 * Create a new resource.  This is in response to a POST request.
	 * @return The identifier of the resource. May not be null. This will be used to
	 * construct a Location URL to the new resource.
	 * @throws DataAccessException If there is a problem in creating the resource.
	 */
	public abstract String create() throws DataAccessException;

	/**
	 * Delete a resource. This is in response to a DELETE request. According to the
	 * HTTP specification this method should be idempotent.
	 */
	public abstract void delete(String id) throws DataAccessException;

	/**
	 * Update the identified resource. This is ni response to a PUT request. The http specification allows for
	 * creating a new resource in response to a put request but this this framework has excluded that possibility.
	 * @param id The resource to update with new values.
	 * @throws DataAccessException If there is a problem saving the new values.
	 * @throws ResourceConflictException If the entity can not be updated because there is a version conflict.
	 */
	public abstract void update(String id) throws DataAccessException, ResourceConflictException;
}
